Form Builder

Form Builder allows developers to construct user entry forms which integrate with IAP (Itential Automation Platform) Workflows and Service Catalog applications. In addition to constructing forms with standard inputs, developers can create forms from imported NSO YANG Service Models using the NSO NETCONF API. This native integration with NSO Services reduces the effort of having to duplicate the development of modeling services in both IAP and NSO. With Form Builder, service models requiring changes are modified just once; changes made in NSO are automatically available for IAP to consume.

User Interface

The following figures show the user interface in Form Builder for the List View and Edit View. A description of each numbered element is provided in the reference table below each image.

List View

Label	UI Element	List View Function
1	New Form	Creates a new form.
2	Delete	Deletes form when check-box has been selected.
3	Form List	List of forms; includes the form name, who created it, when it was created, who last updated it, and when it was last updated.
4	Edit	Opens form for editing.
5	Import Form	Imports a form.
6	Export Forms	Exports each form that is checked in the form list.
7	Edit Forms	Edit, delete and export form.

Edit View

Label	UI Element	Edit View Function
1	Form Name	User must provide unique form name.
2	Data Elements	Displays list of registered NSO services.
3	Meta Data Fields	Allows user to define custom fields in the form.
4	Update	Updates form and leaves Form Editor open.
5	Settings	Opens a modal to change the settings of the form.
6	Preview	Opens a modal to preview the form.
7	Clone	Makes a copy of the current form.
8	Delete Form	Deletes the current form.
9	Add Container/Table	Adds a field container or table to the form.
10	Delete	Deletes the form element.

Creating a New Form

To create a new form:

1. Open Form Builder from the Home page or the Applications menu.
2. Click New Form (top-right corner of title bar).
3. Give the form a unique name.
4. Click Save.

Exporting a Form

To export a single form:

1. Open Form Builder from the Home page or the Applications menu.
2. Locate the form that you wish to export in the forms list.
3. Click the export icon at the far right of a form in the list.

To export multiple forms:

1. Open Form Builder from the Home page or the Applications menu.
2. Click the check box for each form you wish to export.
3. Click Export Forms (top-right corner of title bar).

Importing a Form

To import a form:

1. Open Form Builder from the Home page or the Applications menu.
2. Click Import Form (top-right corner of title bar).
3. Select the form data file you wish to import.
4. Click Open on the file dialog.

NSO Service Model Form Fields

Guidelines

• To view device elements from a service model in Form Builder, you will need to specify where to find the YANG files. In newer versions of NSO adapter (version 4 and higher), this is configured in the yangdirs property of the adapter.
• To view service models in older versions of NSO adapter (pre version 4), include your YANG schemas in the load-path of ncs.conf.
• For more information on configuring the NSO adapter to get YANG, check the NSO NETCONF documentation for the adapter.

Create a Form Using NSO YANG Service Model

The following steps correspond to the labels shown in the figure below. To build a form on an NSO YANG service model:

1. Select the appropriate service from the Data Elements dropdown list.
   • The leafs defined in the model will automatically display below the dropdown box.
2. Drag-and-drop the fields to assign them to the form.
   • By default, the field label is the same as the leaf from the service model. See id in the example figure below.
   • To update the field label, click the field and type a new label.
3. Assign the Lists defined in NSO to the form.
4. Group the fields together within a Container.
   • Click the Add Container button to assign a Container to a Form.
   • Toggle the direction icon (double arrow in left corner) to arrange the Containers horizontally or vertically. Containers can also be nested within other Containers.
5. Assign a name to the Form.
6. Click Save.

Meta Data Fields

In addition to creating a form using the leafs defined in an NSO Yang service model, you can assign Meta Data Fields to a form. Three field types and a checkbox are available.

• Text Box - Allows any characters.
• Number Field - Accepts only numerical values.
• Checkbox - A Boolean field that can be checked or unchecked.
• Dropdown - Accepts one selected option from a dropdown list.

Preview a Form

Once a form is saved, click the Form Preview button (eye icon) in the title bar to preview the form.

All form fields are editable in Preview mode, even those configured as a lead reference or enumeration in the YANG service model, just as they are when the form is allocated to a Workflow. The figure below illustrates the dropdown list generated by an NSO leaf reference.

Enable or Disable Constraints

The Validate Constraints checkbox in Forms allows a user to bypass the must statement validations defined in the YANG service models. The checkbox works at the form level, which means that disabling the checkbox will disable validations for the entire form. The checkbox does not, however, disable other form validations.

Examples

The example below shows a form with a leaf description which has constraints defined for length of the string (it must be between 3 to 8 characters). The leaf is a must statement (leafWithMust) that says the length of the leaf description should be exactly 5.

As seen below, the leaf description has only two characters, hence an error message is displayed for the leaf.

Disabling the Validate Constraints checkbox did not remove the error message for the field as expected.

In the form below, it can be seen that validation of the description field passed since the number of characters is now three, but we can see that the field leafWithMust has failed since it requires the description field to have 5 characters.

However, when the Validate Constraints checkbox is not checked (disabled), validation of the must statement is disabled and now the form reports no errors.

Edit Form Field Properties

Once a field has been allocated to a form, you can configure some of its properties.

1. Hover your mouse over the field.
2. Click the Configure Properties icon (top-right corner). The Configure dialog box opens.

Property	Description
Custom Label	Adds a custom label above the field.
Field Key	An internal value that identifies the field from the underlying workflow engine code. Update this value only for a Meta Data Field. Do not modify this value when the field is part of an NSO YANG service model.
Info/ Tool Tip	Adds a custom tool tip that displays when your cursor is placed over the field.
Required	When checked, a Form cannot be submitted unless a value has been entered in the Number field that displays.
Read-Only	When checked, the field is visible to users but they will not be able to modify the value.
Hide Field	When checked, the field is hidden from users. The field will still be available to the underlying Workflow Engine code.
Min Length	The minimum number of characters a Text field must contain before it can be submitted. Requires the user to define a numeric value.
Max Length	The maximum number of characters a Text field may contain before it can be submitted. Requires the user to define a numeric value.
Regex Patterns	Does not apply to any fields that have been assigned an NSO leaf reference or enumeration.
Custom Error Message	Adds a custom error message that displays when user input is invalid. Requires that Field Type be defined.

Delete a Form Field

To remove a form field, click on the trashcan icon (top right).

Add a Form Builder Task to a Workflow

This section discusses how to add a Form Builder task to a workflow. It does not describe the functionality of the Workflow Builder application.

Note: If you are not familiar with the Workflow Builder application, consult the relevant user guide for clarification on any of the information discussed in this section.

You can use Form Builder to add a Form to a workflow. This allows the user to enter information as part of the business process.

To add a form to a workflow:

1. Create a new workflow, or open an existing one.

2. Select FormBuilder in the Source Application dropdown list.

3. Select ShowFormByName and add it to the workflow.

   Example Task

   

4. Configure the manual task.

   • Enter an appropriate summary and description
   • Assign it to the relevant User Group.

5. Configure the variables for the ShowFormByName task.

   • form_name This variable is the name of the Form.

     • Select static as the Reference task.
     • Enter the name of the Form as the Reference variable.

   • instance_data If the form values are entered by the user and are not populated by a previous task or external system, configure the following:

     • Select static as the Reference task.

     • Enter {} as the Reference variable.

       Edit Task

       

6. Click Update.

7. Save the workflow

8. Click the Start workflow button.

9. Navigate to the Work queue to view the task in the Available Tasks list.

10. Click the task to initiate the work.

Example Service Form from Workflow

Outgoing Data Format Example

{
  "/ncs:services/itential_test_devices:cisco-ios": [
    {
      "device": [
        "csr01-atl"
      ]
    }
  ],
  "/ncs:services/aspan-vrf:aspan-vrf": [
    {
      "vpn-id": 1,
      "vrf-name": "vrfName",
      "route-target": [
        {
          "rt-export": [
            {
              "asn-ip": "1.1.1.2:33"
            }
          ]
        }
      ]
    }
  ]
}

Note: The internal reference to the Form Field retains the original value before it was renamed.